---
title: query touched-files
sidebar_label: touched-files
---

Use the `moon query touched-files` sub-command to query for a list of touched files (added,
modified, deleted, etc) using the current VCS state. These are the same queries that
[`moon ci`](../ci) and [`moon run`](../run) use under the hood.

Touches files are determined using the following logic:

- If `--defaultBranch` is provided, and the current branch is the
  [`vcs.defaultBranch`](../../config/workspace#defaultbranch), then compare against the previous
  revision of the default branch (`HEAD~1`). This is what [continuous integration](../../guides/ci)
  uses.
- If `--local` is provided, touched files are based on your local index only (`git status`).
- Otherwise, then compare the defined base (`--base`) against head (`--head`).

```shell
# Return all files
$ moon query touched-files

# Return deleted files
$ moon query touched-files --status deleted

# Return all files between 2 revisions
$ moon query touched-files --base <branch> --head <commit>
```

By default, this will output a list of absolute file paths, separated by new lines.

```
/absolute/file/one.ts
/absolute/file/two.ts
```

The files can also be output in JSON by passing the `--json` flag. The output has the following
structure:

```ts
{
	files: string[],
	options: QueryOptions,
}
```

### Options

- `--defaultBranch` - When on the default branch, compare against the previous revision.
- `--base <rev>` - Base branch, commit, or revision to compare against. Defaults to
  [`vcs.defaultBranch`](../../config/workspace#defaultbranch).
- `--head <rev>` - Current branch, commit, or revision to compare with. Defaults to `HEAD`.
- `--json` - Display the files in JSON format.
- `--local` - Gather files from the local state instead of remote.
- `--remote` - Gather files from the remote state instead of local.
- `--status <type>` - Filter files based on a touched status. Can be passed multiple times.
  - Types: `all` (default), `added`, `deleted`, `modified`, `staged`, `unstaged`, `untracked`

### Configuration

- [`vcs`](../../config/workspace#vcs) in `.moon/workspace.yml`
